<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>JSON Voorhees: Overview</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/x-mathjax-config">
  MathJax.Hub.Config({
    extensions: ["tex2jax.js"],
    jax: ["input/TeX","output/HTML-CSS"],
});
</script><script type="text/javascript" src="http://www.mathjax.org/mathjax/MathJax.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">JSON Voorhees
   </div>
   <div id="projectbrief">Killer JSON for C++</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('index.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Overview </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>JSON Voorhees is a JSON library written for the C++ programmer who wants to be productive in this modern world. What does that mean? There are a ton of JSON libraries floating around touting how they are "modern" C++ and so on. But who really cares? JSON Voorhees puts the focus more on the resulting C++ than any "modern" feature set. This means the library does not skip on string encoding details like having full support for UTF-8. Are there "modern" features? Sure, but this library is not meant to be a gallery of them &ndash; a good API should get out of your way and let you work. It is hosted on <a href="https://github.com/tgockel/json-voorhees">GitHub</a> and sports an Apache License, so use it anywhere you need.</p>
<p>Features include (but are not necessarily limited to):</p>
<ul>
<li>Simple<ul>
<li>A <code>value</code> should not feel terribly different from a C++ Standard Library container</li>
<li>Write valid JSON with <code>operator&lt;&lt;</code></li>
<li>Simple JSON parsing with <code>parse</code></li>
<li>Reasonable error messages when parsing fails</li>
<li>Full support for Unicode-filled JSON (encoded in UTF-8 in C++)</li>
</ul>
</li>
<li>Efficient<ul>
<li>Minimal overhead to store values (a <code>value</code> is 16 bytes on a 64-bit platform)</li>
<li>No-throw move semantics wherever possible</li>
</ul>
</li>
<li>Easy<ul>
<li>Convert a <code>value</code> into a C++ type using <code>extract&lt;T&gt;</code></li>
<li>Encode a C++ type into a value using <code>to_json</code></li>
</ul>
</li>
<li>Safe<ul>
<li>In the best case, illegal code should fail to compile</li>
<li>An illegal action should throw an exception</li>
<li>Almost all utility functions have a <a href="http://www.gotw.ca/gotw/082.htm">strong exception guarantee</a>.</li>
</ul>
</li>
<li>Stable<ul>
<li>Worry less about upgrading &ndash; the API and ABI will not change out from under you</li>
</ul>
</li>
<li>Documented<ul>
<li>Consumable by human beings</li>
<li>Answers questions you might actually ask</li>
</ul>
</li>
</ul>
<p><div class="dotgraph">
<iframe scrolling="no" frameborder="0" src="dot_conversions.svg" width="460" height="322"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe></div>
</p>
<p>JSON Voorhees is designed with ease-of-use in mind. So let's look at some code!</p>
<h1><a class="anchor" id="demo_value"></a>
The jsonv::value</h1>
<p>The central class of JSON Voorhees is the <code><a class="el" href="classjsonv_1_1value.html" title="Represents a single JSON value, which can be any one of a potential kind, each behaving slightly diff...">jsonv::value</a></code>. This class represents a JSON AST and is somewhat of a dynamic type. This can make things a little bit awkward for C++ programmers who are used to static typing. Don't worry about it &ndash; you can learn to love it.</p>
<p>Putting values of different types is super-easy.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="value_8hpp.html">jsonv/value.hpp</a>&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;iostream&gt;</span></div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main()</div><div class="line">{</div><div class="line">    <a class="code" href="classjsonv_1_1value.html">jsonv::value</a> x = <a class="code" href="group__Value.html#gadfc02eaef2e93e367cb9f2922cdfe490">jsonv::null</a>;</div><div class="line">    std::cout &lt;&lt; x &lt;&lt; std::endl;</div><div class="line">    x = 5.9;</div><div class="line">    std::cout &lt;&lt; x &lt;&lt; std::endl;</div><div class="line">    x = -100;</div><div class="line">    std::cout &lt;&lt; x &lt;&lt; std::endl;</div><div class="line">    x = <span class="stringliteral">&quot;something else&quot;</span>;</div><div class="line">    std::cout &lt;&lt; x &lt;&lt; std::endl;</div><div class="line">    x = <a class="code" href="group__Value.html#ga8c4ac5022703a328eddc667d4ce333ed">jsonv::array</a>({ <span class="stringliteral">&quot;arrays&quot;</span>, <span class="stringliteral">&quot;of&quot;</span>, <span class="stringliteral">&quot;the&quot;</span>, 7, <span class="stringliteral">&quot;different&quot;</span>, <span class="stringliteral">&quot;types&quot;</span>});</div><div class="line">    std::cout &lt;&lt; x &lt;&lt; std::endl;</div><div class="line">    x = <a class="code" href="group__Value.html#gabae5c5bfa8dceec8849cfe0a58ad83b1">jsonv::object</a>({</div><div class="line">                        { <span class="stringliteral">&quot;objects&quot;</span>, <a class="code" href="group__Value.html#ga8c4ac5022703a328eddc667d4ce333ed">jsonv::array</a>({</div><div class="line">                                                   <span class="stringliteral">&quot;Are fun, too.&quot;</span>,</div><div class="line">                                                   <span class="stringliteral">&quot;Do what you want.&quot;</span></div><div class="line">                                                 })</div><div class="line">                        },</div><div class="line">                        { <span class="stringliteral">&quot;compose like&quot;</span>, <span class="stringliteral">&quot;standard library maps&quot;</span> },</div><div class="line">                     });</div><div class="line">    std::cout &lt;&lt; x &lt;&lt; std::endl;</div><div class="line">}</div></div><!-- fragment --><p>Output:</p>
<div class="fragment"><div class="line"><a class="code" href="group__Value.html#gadfc02eaef2e93e367cb9f2922cdfe490">null</a></div><div class="line">5.9</div><div class="line">-100</div><div class="line"><span class="stringliteral">&quot;something else&quot;</span></div><div class="line">[<span class="stringliteral">&quot;arrays&quot;</span>,<span class="stringliteral">&quot;of&quot;</span>,<span class="stringliteral">&quot;the&quot;</span>,7,<span class="stringliteral">&quot;different&quot;</span>,<span class="stringliteral">&quot;types&quot;</span>]</div><div class="line">{<span class="stringliteral">&quot;compose like&quot;</span>:<span class="stringliteral">&quot;standard library maps&quot;</span>,<span class="stringliteral">&quot;objects&quot;</span>:[<span class="stringliteral">&quot;Are fun, too.&quot;</span>,<span class="stringliteral">&quot;Do what you want.&quot;</span>]}</div></div><!-- fragment --><p>If that isn't convenient enough for you, there is a user-defined literal <code>_json</code> in the <code>jsonv</code> namespace you can use</p>
<div class="fragment"><div class="line"><span class="comment">// You can use this hideous syntax if you do not want to bring in the whole jsonv namespace:</span></div><div class="line"><span class="keyword">using</span> jsonv::operator<span class="stringliteral">&quot;&quot;</span> _json;</div><div class="line"></div><div class="line"><a class="code" href="classjsonv_1_1value.html">jsonv::value</a> x = R<span class="stringliteral">&quot;({</span></div><div class="line"><span class="stringliteral">                      &quot;objects&quot;: [ &quot;Are fun, too.&quot;,</span></div><div class="line"><span class="stringliteral">                                   &quot;Do what you want.&quot;</span></div><div class="line"><span class="stringliteral">                                 ],</span></div><div class="line"><span class="stringliteral">                      &quot;compose like&quot;: &quot;You are just writing JSON&quot;,</span></div><div class="line"><span class="stringliteral">                      &quot;which I guess&quot;: [&quot;is&quot;, &quot;also&quot;, &quot;neat&quot;]</span></div><div class="line"><span class="stringliteral">                   })&quot;_json;</span></div></div><!-- fragment --><p>JSON is dynamic, which makes value access a bit more of a hassle, but JSON Voorhees aims to make it not too horrifying for you. A <code><a class="el" href="classjsonv_1_1value.html" title="Represents a single JSON value, which can be any one of a potential kind, each behaving slightly diff...">jsonv::value</a></code> has a number of accessor methods named things like <code>as_integer</code> and <code>as_string</code> which let you access the value as if it was that type. But what if it isn't that type? In that case, the function will throw a <code><a class="el" href="classjsonv_1_1kind__error.html" title="Thrown from various value methods when attempting to perform an operation which is not valid for the ...">jsonv::kind_error</a></code> with a bit more information as to what rule you violated.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="value_8hpp.html">jsonv/value.hpp</a>&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;iostream&gt;</span></div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main()</div><div class="line">{</div><div class="line">    <a class="code" href="classjsonv_1_1value.html">jsonv::value</a> x = <a class="code" href="group__Value.html#gadfc02eaef2e93e367cb9f2922cdfe490">jsonv::null</a>;</div><div class="line">    <span class="keywordflow">try</span></div><div class="line">    {</div><div class="line">        x.<a class="code" href="classjsonv_1_1value.html#a857ab3adbc33de720eb37d8bc8a2a0bb">as_string</a>();</div><div class="line">    }</div><div class="line">    <span class="keywordflow">catch</span> (<span class="keyword">const</span> <a class="code" href="classjsonv_1_1kind__error.html">jsonv::kind_error</a>&amp; err)</div><div class="line">    {</div><div class="line">        std::cout &lt;&lt; err.what() &lt;&lt; std::endl;</div><div class="line">    }</div><div class="line">    </div><div class="line">    x = <span class="stringliteral">&quot;now make it a string&quot;</span>;</div><div class="line">    std::cout &lt;&lt; x.<a class="code" href="classjsonv_1_1value.html#a857ab3adbc33de720eb37d8bc8a2a0bb">as_string</a>().size() &lt;&lt; std::endl;</div><div class="line">    std::cout &lt;&lt; x.<a class="code" href="classjsonv_1_1value.html#a857ab3adbc33de720eb37d8bc8a2a0bb">as_string</a>() &lt;&lt; <span class="stringliteral">&quot;\tis not the same as\t&quot;</span> &lt;&lt; x &lt;&lt; std::endl;</div><div class="line">}</div></div><!-- fragment --><p>Output:</p>
<div class="fragment"><div class="line">Unexpected type: expected <span class="keywordtype">string</span> but found <a class="code" href="group__Value.html#gadfc02eaef2e93e367cb9f2922cdfe490">null</a>.</div><div class="line">20</div><div class="line">now make it a <span class="keywordtype">string</span>    is not the same as  <span class="stringliteral">&quot;now make it a string&quot;</span></div></div><!-- fragment --><p>You can also deal with container types in a similar manner that you would deal with the equivalent STL container type, with some minor caveats. Because the <code>value_type</code> of a JSON object and JSON array are different, they have different iterator types in JSON Voorhees. They are aptly-named <code>object_iterator</code> and <code>array_iterator</code>. The access methods for these iterators are <code>begin_object</code> / <code>end_object</code> and <code>begin_array</code> / <code>end_array</code>, respectively. The object interface behaves exactly like you would expect a <code>std::map&lt;std::string,jsonv::value&gt;</code> to, while the array interface behaves just like a <code>std::deque&lt;jsonv::value&gt;</code> would.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="value_8hpp.html">jsonv/value.hpp</a>&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;iostream&gt;</span></div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main()</div><div class="line">{</div><div class="line">    <a class="code" href="classjsonv_1_1value.html">jsonv::value</a> x = <a class="code" href="group__Value.html#gabae5c5bfa8dceec8849cfe0a58ad83b1">jsonv::object</a>({ { <span class="stringliteral">&quot;one&quot;</span>, 1 }});</div><div class="line">    <span class="keyword">auto</span> iter = x.<a class="code" href="classjsonv_1_1value.html#a765ff56aa009ddea1a7360f0f9acb93a">find</a>(<span class="stringliteral">&quot;one&quot;</span>);</div><div class="line">    <span class="keywordflow">if</span> (iter != x.<a class="code" href="classjsonv_1_1value.html#a4575cef7e4195a25eeba35a7f15b2fbd">end_object</a>())</div><div class="line">        std::cout &lt;&lt; iter-&gt;first &lt;&lt; <span class="stringliteral">&quot;: &quot;</span> &lt;&lt; iter-&gt;second &lt;&lt; std::endl;</div><div class="line">    <span class="keywordflow">else</span></div><div class="line">        std::cout &lt;&lt; <span class="stringliteral">&quot;Nothing...&quot;</span> &lt;&lt; std::end;</div><div class="line">    </div><div class="line">    iter = x.<a class="code" href="classjsonv_1_1value.html#a765ff56aa009ddea1a7360f0f9acb93a">find</a>(<span class="stringliteral">&quot;two&quot;</span>);</div><div class="line">    <span class="keywordflow">if</span> (iter != x.<a class="code" href="classjsonv_1_1value.html#a4575cef7e4195a25eeba35a7f15b2fbd">end_object</a>())</div><div class="line">        std::cout &lt;&lt; iter-&gt;first &lt;&lt; <span class="stringliteral">&quot;: &quot;</span> &lt;&lt; iter-&gt;second &lt;&lt; std::endl;</div><div class="line">    <span class="keywordflow">else</span></div><div class="line">        std::cout &lt;&lt; <span class="stringliteral">&quot;Nothing...&quot;</span> &lt;&lt; std::end;</div><div class="line">    </div><div class="line">    x[<span class="stringliteral">&quot;two&quot;</span>] = 2;</div><div class="line">    iter = x.<a class="code" href="classjsonv_1_1value.html#a765ff56aa009ddea1a7360f0f9acb93a">find</a>(<span class="stringliteral">&quot;two&quot;</span>);</div><div class="line">    <span class="keywordflow">if</span> (iter != x.<a class="code" href="classjsonv_1_1value.html#a4575cef7e4195a25eeba35a7f15b2fbd">end_object</a>())</div><div class="line">        std::cout &lt;&lt; iter-&gt;first &lt;&lt; <span class="stringliteral">&quot;: &quot;</span> &lt;&lt; iter-&gt;second &lt;&lt; std::endl;</div><div class="line">    <span class="keywordflow">else</span></div><div class="line">        std::cout &lt;&lt; <span class="stringliteral">&quot;Nothing...&quot;</span> &lt;&lt; std::end;</div><div class="line">    </div><div class="line">    x[<span class="stringliteral">&quot;two&quot;</span>] = jsonv::array({ <span class="stringliteral">&quot;one&quot;</span>, <span class="stringliteral">&quot;+&quot;</span>, x.<a class="code" href="classjsonv_1_1value.html#ad1978289ca5b93314f1faf54787d3e22">at</a>(<span class="stringliteral">&quot;one&quot;</span>) });</div><div class="line">    iter = x.<a class="code" href="classjsonv_1_1value.html#a765ff56aa009ddea1a7360f0f9acb93a">find</a>(<span class="stringliteral">&quot;two&quot;</span>);</div><div class="line">    <span class="keywordflow">if</span> (iter != x.<a class="code" href="classjsonv_1_1value.html#a4575cef7e4195a25eeba35a7f15b2fbd">end_object</a>())</div><div class="line">        std::cout &lt;&lt; iter-&gt;first &lt;&lt; <span class="stringliteral">&quot;: &quot;</span> &lt;&lt; iter-&gt;second &lt;&lt; std::endl;</div><div class="line">    <span class="keywordflow">else</span></div><div class="line">        std::cout &lt;&lt; <span class="stringliteral">&quot;Nothing...&quot;</span> &lt;&lt; std::end;</div><div class="line">    </div><div class="line">    x.<a class="code" href="classjsonv_1_1value.html#a7b480563d0e93fc21018e088ac38646d">erase</a>(<span class="stringliteral">&quot;one&quot;</span>);</div><div class="line">    iter = x.<a class="code" href="classjsonv_1_1value.html#a765ff56aa009ddea1a7360f0f9acb93a">find</a>(<span class="stringliteral">&quot;one&quot;</span>);</div><div class="line">    <span class="keywordflow">if</span> (iter != x.<a class="code" href="classjsonv_1_1value.html#a4575cef7e4195a25eeba35a7f15b2fbd">end_object</a>())</div><div class="line">        std::cout &lt;&lt; iter-&gt;first &lt;&lt; <span class="stringliteral">&quot;: &quot;</span> &lt;&lt; iter-&gt;second &lt;&lt; std::endl;</div><div class="line">    <span class="keywordflow">else</span></div><div class="line">        std::cout &lt;&lt; <span class="stringliteral">&quot;Nothing...&quot;</span> &lt;&lt; std::end;</div><div class="line">}</div></div><!-- fragment --><p>Output:</p>
<div class="fragment"><div class="line">one: 1</div><div class="line">Nothing...</div><div class="line">two: 2</div><div class="line">two: [<span class="stringliteral">&quot;one&quot;</span>,<span class="stringliteral">&quot;+&quot;</span>,1]</div><div class="line">Nothing...</div></div><!-- fragment --><p>The iterator types <em>work</em>. This means you are free to use all of the C++ things just like you would a regular container. To use a ranged-based for, simply call <code>as_array</code> or <code>as_object</code>. Everything from <code></code> &lt;algorithm&gt; and <code></code> &lt;iterator&gt; or any other library works great with JSON Voorhees. Bring those templates on!</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="value_8hpp.html">jsonv/value.hpp</a>&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;algorithm&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;iostream&gt;</span></div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main()</div><div class="line">{</div><div class="line">    <a class="code" href="classjsonv_1_1value.html">jsonv::value</a> arr = <a class="code" href="group__Value.html#ga8c4ac5022703a328eddc667d4ce333ed">jsonv::array</a>({ <span class="stringliteral">&quot;taco&quot;</span>, <span class="stringliteral">&quot;cat&quot;</span>, 3, -2, <a class="code" href="group__Value.html#gadfc02eaef2e93e367cb9f2922cdfe490">jsonv::null</a>, <span class="stringliteral">&quot;beef&quot;</span>, 4.8, 5 });</div><div class="line">    std::cout &lt;&lt; <span class="stringliteral">&quot;Initial: &quot;</span>;</div><div class="line">    <span class="keywordflow">for</span> (<span class="keyword">const</span> <span class="keyword">auto</span>&amp; val : arr.<a class="code" href="classjsonv_1_1value.html#a410e0768e350ebfdccc853da11a975e5">as_array</a>())</div><div class="line">        std::cout &lt;&lt; val &lt;&lt; <span class="charliteral">&#39;\t&#39;</span>;</div><div class="line">    std::cout &lt;&lt; std::endl;</div><div class="line">    </div><div class="line">    std::sort(arr.<a class="code" href="classjsonv_1_1value.html#ae8a94ae8199b6de18e9e27347b6a2dd7">begin_array</a>(), arr.<a class="code" href="classjsonv_1_1value.html#ae8e46475135847419326f43bb8652030">end_array</a>());</div><div class="line">    std::cout &lt;&lt; <span class="stringliteral">&quot;Sorted: &quot;</span>;</div><div class="line">    <span class="keywordflow">for</span> (<span class="keyword">const</span> <span class="keyword">auto</span>&amp; val : arr.<a class="code" href="classjsonv_1_1value.html#a410e0768e350ebfdccc853da11a975e5">as_array</a>())</div><div class="line">        std::cout &lt;&lt; val &lt;&lt; <span class="charliteral">&#39;\t&#39;</span>;</div><div class="line">    std::cout &lt;&lt; std::endl;</div><div class="line">}</div></div><!-- fragment --><p>Output:</p>
<div class="fragment"><div class="line">Initial: <span class="stringliteral">&quot;taco&quot;</span> <span class="stringliteral">&quot;cat&quot;</span>   3   -2  <a class="code" href="group__Value.html#gadfc02eaef2e93e367cb9f2922cdfe490">null</a>    <span class="stringliteral">&quot;beef&quot;</span>  4.8   5</div><div class="line">Sorted:  <a class="code" href="group__Value.html#gadfc02eaef2e93e367cb9f2922cdfe490">null</a>   -2  3   4.8 5   <span class="stringliteral">&quot;beef&quot;</span>  <span class="stringliteral">&quot;cat&quot;</span>   <span class="stringliteral">&quot;taco&quot;</span></div></div><!-- fragment --><h1><a class="anchor" id="demo_parsing"></a>
Encoding and decoding</h1>
<p>Usually, the reason people are using JSON is as a data exchange format, either for communicating with other services or storing things in a file or a database. To do this, you need to <em>encode</em> your <code>json::value</code> into an <code>std::string</code> and <em>parse</em> it back. JSON Voorhees makes this very easy for you.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="value_8hpp.html">jsonv/value.hpp</a>&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="encode_8hpp.html">jsonv/encode.hpp</a>&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="parse_8hpp.html">jsonv/parse.hpp</a>&gt;</span></div><div class="line"></div><div class="line"><span class="preprocessor">#include &lt;iostream&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;fstream&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;limits&gt;</span></div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main()</div><div class="line">{</div><div class="line">    <a class="code" href="classjsonv_1_1value.html">jsonv::value</a> obj = <a class="code" href="group__Value.html#gabae5c5bfa8dceec8849cfe0a58ad83b1">jsonv::object</a>();</div><div class="line">    obj[<span class="stringliteral">&quot;taco&quot;</span>]  = <span class="stringliteral">&quot;cat&quot;</span>;</div><div class="line">    obj[<span class="stringliteral">&quot;array&quot;</span>] = <a class="code" href="group__Value.html#ga8c4ac5022703a328eddc667d4ce333ed">jsonv::array</a>({ 1, 2, 3, 4, 5 });</div><div class="line">    obj[<span class="stringliteral">&quot;infinity&quot;</span>] = std::numeric_limits&lt;double&gt;::infinity();</div><div class="line">    </div><div class="line">    {</div><div class="line">        std::cout &lt;&lt; <span class="stringliteral">&quot;Saving \&quot;file.json\&quot;... &quot;</span> &lt;&lt; obj &lt;&lt; std::endl;</div><div class="line">        std::ofstream file(<span class="stringliteral">&quot;file.json&quot;</span>);</div><div class="line">        file &lt;&lt; obj;</div><div class="line">    }</div><div class="line">    </div><div class="line">    <a class="code" href="classjsonv_1_1value.html">jsonv::value</a> loaded;</div><div class="line">    {</div><div class="line">        std::cout &lt;&lt; <span class="stringliteral">&quot;Loading \&quot;file.json\&quot;...&quot;</span>;</div><div class="line">        std::ifstream file(<span class="stringliteral">&quot;file.json&quot;</span>);</div><div class="line">        loaded = jsonv::parse(file);</div><div class="line">    }</div><div class="line">    std::cout &lt;&lt; loaded &lt;&lt; std::endl;</div><div class="line">    </div><div class="line">    <span class="keywordflow">return</span> obj == loaded ? 0 : 1;</div><div class="line">}</div></div><!-- fragment --><p>Output:</p>
<div class="fragment"><div class="line">Saving <span class="stringliteral">&quot;file.json&quot;</span>... {<span class="stringliteral">&quot;array&quot;</span>:[1,2,3,4,5],<span class="stringliteral">&quot;infinity&quot;</span>:<a class="code" href="group__Value.html#gadfc02eaef2e93e367cb9f2922cdfe490">null</a>,<span class="stringliteral">&quot;taco&quot;</span>:<span class="stringliteral">&quot;cat&quot;</span>}</div><div class="line">Loading <span class="stringliteral">&quot;file.json&quot;</span>...{<span class="stringliteral">&quot;array&quot;</span>:[1,2,3,4,5],<span class="stringliteral">&quot;infinity&quot;</span>:<a class="code" href="group__Value.html#gadfc02eaef2e93e367cb9f2922cdfe490">null</a>,<span class="stringliteral">&quot;taco&quot;</span>:<span class="stringliteral">&quot;cat&quot;</span>}</div></div><!-- fragment --><p>If you are paying close attention, you might have noticed that the value for the <code>"infinity"</code> looks a little bit more <code>null</code> than <code>infinity</code>. This is because, much like mathematicians before Anaximander, JSON has no concept of infinity, so it is actually <em>illegal</em> to serialize a token like <code>infinity</code> anywhere. By default, when an encoder encounters an unrepresentable value in the JSON it is trying to encode, it outputs <code>null</code> instead. If you wish to change this behavior, implement your own <code><a class="el" href="classjsonv_1_1encoder.html" title="An encoder is responsible for writing values to some form of output. ">jsonv::encoder</a></code> (or derive from <code><a class="el" href="classjsonv_1_1ostream__encoder.html" title="An encoder that outputs to an std::ostream. ">jsonv::ostream_encoder</a></code>). If you ran the example program, you might have noticed that the return code was 1, meaning the value you put into the file and what you got from it were not equal. This is because all the type and value information is still kept around in the in-memory <code>obj</code>. It is only upon encoding that information is lost.</p>
<p>Getting tired of all this compact rendering of your JSON strings? Want a little more whitespace in your life? Then <code><a class="el" href="classjsonv_1_1ostream__pretty__encoder.html">jsonv::ostream_pretty_encoder</a></code> is the class for you! Unlike our standard <em>compact</em> encoder, this guy will put newlines and indentation in your JSON so you can present it in a way more readable format.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="encode_8hpp.html">jsonv/encode.hpp</a>&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="parse_8hpp.html">jsonv/parse.hpp</a>&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="value_8hpp.html">jsonv/value.hpp</a>&gt;</span></div><div class="line"></div><div class="line"><span class="preprocessor">#include &lt;iostream&gt;</span></div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main()</div><div class="line">{</div><div class="line">    <span class="comment">// Make a pretty encoder and point to std::cout</span></div><div class="line">    <a class="code" href="classjsonv_1_1ostream__pretty__encoder.html">jsonv::ostream_pretty_encoder</a> prettifier(std::cout);</div><div class="line">    prettifier.encode(jsonv::parse(std::cin));</div><div class="line">}</div></div><!-- fragment --><p>Compile that code and you now have your own little JSON prettification program!</p>
<h1><a class="anchor" id="serialization"></a>
Serialization</h1>
<p>Most of the time, you do not want to deal with <code><a class="el" href="classjsonv_1_1value.html" title="Represents a single JSON value, which can be any one of a potential kind, each behaving slightly diff...">jsonv::value</a></code> instances directly. Instead, most people prefer to convert <code><a class="el" href="classjsonv_1_1value.html" title="Represents a single JSON value, which can be any one of a potential kind, each behaving slightly diff...">jsonv::value</a></code> instances into their own strong C++ <code>class</code> or <code>struct</code>. JSON Voorhees provides utilities to make this easy for you to use. At the end of the day, you should be able to create an arbitrary C++ type with <code>jsonv::extract&lt;my_type&gt;(value)</code> and create a <code><a class="el" href="classjsonv_1_1value.html" title="Represents a single JSON value, which can be any one of a potential kind, each behaving slightly diff...">jsonv::value</a></code> from your arbitrary C++ type with <code>jsonv::to_json(my_instance)</code>.</p>
<h2><a class="anchor" id="serialization_encoding"></a>
Extracting with extract</h2>
<p>Let's start with converting a <code><a class="el" href="classjsonv_1_1value.html" title="Represents a single JSON value, which can be any one of a potential kind, each behaving slightly diff...">jsonv::value</a></code> into a custom C++ type with <code>jsonv::extract&lt;T&gt;</code>.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="parse_8hpp.html">jsonv/parse.hpp</a>&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="serialization_8hpp.html">jsonv/serialization.hpp</a>&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="value_8hpp.html">jsonv/value.hpp</a>&gt;</span></div><div class="line"></div><div class="line"><span class="preprocessor">#include &lt;iostream&gt;</span></div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main()</div><div class="line">{</div><div class="line">    <a class="code" href="classjsonv_1_1value.html">jsonv::value</a> val = jsonv::parse(R<span class="stringliteral">&quot;({ &quot;a&quot;: 1, &quot;b&quot;: 2, &quot;c&quot;: &quot;Hello!&quot; })&quot;);</span></div><div class="line"><span class="stringliteral">    std::cout &lt;&lt; </span><span class="stringliteral">&quot;a=&quot;</span> &lt;&lt; jsonv::extract&lt;int&gt;(val.<a class="code" href="classjsonv_1_1value.html#ad1978289ca5b93314f1faf54787d3e22">at</a>(<span class="stringliteral">&quot;a&quot;</span>)) &lt;&lt; std::endl;</div><div class="line">    std::cout &lt;&lt; <span class="stringliteral">&quot;b=&quot;</span> &lt;&lt; jsonv::extract&lt;int&gt;(val.<a class="code" href="classjsonv_1_1value.html#ad1978289ca5b93314f1faf54787d3e22">at</a>(<span class="stringliteral">&quot;b&quot;</span>)) &lt;&lt; std::endl;</div><div class="line">    std::cout &lt;&lt; <span class="stringliteral">&quot;c=&quot;</span> &lt;&lt; jsonv::extract&lt;std::string&gt;(val.<a class="code" href="classjsonv_1_1value.html#ad1978289ca5b93314f1faf54787d3e22">at</a>(<span class="stringliteral">&quot;c&quot;</span>)) &lt;&lt; std::endl;</div><div class="line">}</div></div><!-- fragment --><p>Output:</p>
<div class="fragment"><div class="line">a=1</div><div class="line">b=2</div><div class="line">c=Hello!</div></div><!-- fragment --><p>Overall, this is not very complicated. We did not do anything that could not have been done through a little use of <code>as_integer</code> and <code>as_string</code>. So what is this <code>extract</code> giving us?</p>
<p>The real power comes in when we start talking about <code><a class="el" href="classjsonv_1_1formats.html" title="Simply put, this class is a collection of extractor and serializer instances. ">jsonv::formats</a></code>. These objects provide a set of rules to encode and decode arbitrary types. So let's make a C++ <code>class</code> for our JSON object and write a special constructor for it.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="parse_8hpp.html">jsonv/parse.hpp</a>&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="serialization_8hpp.html">jsonv/serialization.hpp</a>&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="serialization__util_8hpp.html">jsonv/serialization_util.hpp</a>&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="value_8hpp.html">jsonv/value.hpp</a>&gt;</span></div><div class="line"></div><div class="line"><span class="preprocessor">#include &lt;iostream&gt;</span></div><div class="line"></div><div class="line"><span class="keyword">class </span>my_type</div><div class="line">{</div><div class="line"><span class="keyword">public</span>:</div><div class="line">    my_type(<span class="keyword">const</span> <a class="code" href="classjsonv_1_1value.html">jsonv::value</a>&amp; from, <span class="keyword">const</span> <a class="code" href="classjsonv_1_1extraction__context.html">jsonv::extraction_context</a>&amp; context) :</div><div class="line">            a(context.extract_sub&lt;int&gt;(from, <span class="stringliteral">&quot;a&quot;</span>)),</div><div class="line">            b(context.extract_sub&lt;int&gt;(from, <span class="stringliteral">&quot;b&quot;</span>)),</div><div class="line">            c(context.extract_sub&lt;<a class="code" href="namespacestd.html">std</a>::string&gt;(from, <span class="stringliteral">&quot;c&quot;</span>))</div><div class="line">    { }</div><div class="line">    </div><div class="line">    <span class="keyword">static</span> <span class="keyword">const</span> <a class="code" href="classjsonv_1_1extractor.html">jsonv::extractor</a>* get_extractor()</div><div class="line">    {</div><div class="line">        <span class="keyword">static</span> <a class="code" href="classjsonv_1_1extractor__construction.html">jsonv::extractor_construction&lt;my_type&gt;</a> instance;</div><div class="line">        <span class="keywordflow">return</span> &amp;instance;</div><div class="line">    }</div><div class="line">    </div><div class="line">    <span class="keyword">friend</span> std::ostream&amp; operator&lt;&lt;(std::ostream&amp; os, <span class="keyword">const</span> my_type&amp; <span class="keyword">self</span>)</div><div class="line">    {</div><div class="line">        <span class="keywordflow">return</span> os &lt;&lt; <span class="stringliteral">&quot;{ a=&quot;</span> &lt;&lt; <span class="keyword">self</span>.a &lt;&lt; <span class="stringliteral">&quot;, b=&quot;</span> &lt;&lt; <span class="keyword">self</span>.b &lt;&lt; <span class="stringliteral">&quot;, c=&quot;</span> &lt;&lt; <span class="keyword">self</span>.c &lt;&lt; <span class="stringliteral">&quot; }&quot;</span>;</div><div class="line">    }</div><div class="line">    </div><div class="line"><span class="keyword">private</span>:</div><div class="line">    <span class="keywordtype">int</span>         a;</div><div class="line">    <span class="keywordtype">int</span>         b;</div><div class="line">    std::string c;</div><div class="line">};</div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main()</div><div class="line">{</div><div class="line">    <a class="code" href="classjsonv_1_1formats.html">jsonv::formats</a> local_formats;</div><div class="line">    local_formats.<a class="code" href="classjsonv_1_1formats.html#aaf6e36e4e7edc4702294a4e039113c62">register_extractor</a>(my_type::get_extractor());</div><div class="line">    <a class="code" href="classjsonv_1_1formats.html">jsonv::formats</a> format = <a class="code" href="classjsonv_1_1formats.html#ae8fdc86436f8dcfd405753db55620110">jsonv::formats::compose</a>({ <a class="code" href="classjsonv_1_1formats.html#ad194791e293229fb6a79438a6444f51b">jsonv::formats::defaults</a>(), local_formats });</div><div class="line">    </div><div class="line">    <a class="code" href="classjsonv_1_1value.html">jsonv::value</a> val = jsonv::parse(R<span class="stringliteral">&quot;({ &quot;a&quot;: 1, &quot;b&quot;: 2, &quot;c&quot;: &quot;Hello!&quot; })&quot;);</span></div><div class="line"><span class="stringliteral">    my_type x = jsonv::extract&lt;my_type&gt;(val, format);</span></div><div class="line"><span class="stringliteral">    std::ostream &lt;&lt; x &lt;&lt; std::endl;</span></div><div class="line"><span class="stringliteral">}</span></div></div><!-- fragment --><p>Output:</p>
<div class="fragment"><div class="line">{ a=1, b=2, c=Hello! }</div></div><!-- fragment --><p>There is a lot going on in that example, so let's take it one step at a time. First, we are creating a <code>my_type</code> object to store our values, which is nice. Then, we gave it a funny-looking constructor:</p>
<div class="fragment"><div class="line">my_type(<span class="keyword">const</span> <a class="code" href="classjsonv_1_1value.html">jsonv::value</a>&amp; from, <span class="keyword">const</span> <a class="code" href="classjsonv_1_1extraction__context.html">jsonv::extraction_context</a>&amp; context) :</div><div class="line">        a(context.extract_sub&lt;int&gt;(from, <span class="stringliteral">&quot;a&quot;</span>)),</div><div class="line">        b(context.extract_sub&lt;int&gt;(from, <span class="stringliteral">&quot;b&quot;</span>)),</div><div class="line">        c(context.extract_sub&lt;<a class="code" href="namespacestd.html">std</a>::string&gt;(from, <span class="stringliteral">&quot;c&quot;</span>))</div><div class="line">{ }</div></div><!-- fragment --><p>This is an <em>extracting constructor</em>. All that means is that it has those two arguments: a <code><a class="el" href="classjsonv_1_1value.html" title="Represents a single JSON value, which can be any one of a potential kind, each behaving slightly diff...">jsonv::value</a></code> and a <code><a class="el" href="classjsonv_1_1extraction__context.html">jsonv::extraction_context</a></code>. The <code><a class="el" href="classjsonv_1_1extraction__context.html">jsonv::extraction_context</a></code> is an optional, but extremely helpful class. Inside the constructor, we use the <code><a class="el" href="classjsonv_1_1extraction__context.html">jsonv::extraction_context</a></code> to access the values of the incoming JSON object in order to build our object.</p>
<div class="fragment"><div class="line"><span class="keyword">static</span> <span class="keyword">const</span> <a class="code" href="classjsonv_1_1extractor.html">jsonv::extractor</a>* get_extractor()</div><div class="line">{</div><div class="line">    <span class="keyword">static</span> <a class="code" href="classjsonv_1_1extractor__construction.html">jsonv::extractor_construction&lt;my_type&gt;</a> instance;</div><div class="line">    <span class="keywordflow">return</span> &amp;instance;</div><div class="line">}</div></div><!-- fragment --><p>A <code><a class="el" href="classjsonv_1_1extractor.html" title="An extractor holds the method for converting a value into an arbitrary C++ type. ">jsonv::extractor</a></code> is a type that knows how to take a <code><a class="el" href="classjsonv_1_1value.html" title="Represents a single JSON value, which can be any one of a potential kind, each behaving slightly diff...">jsonv::value</a></code> and create some C++ type out of it. In this case, we are creating a <code><a class="el" href="classjsonv_1_1extractor__construction.html">jsonv::extractor_construction</a></code>, which is a subtype that knows how to call the constructor of a type. There are all sorts of <code><a class="el" href="classjsonv_1_1extractor.html" title="An extractor holds the method for converting a value into an arbitrary C++ type. ">jsonv::extractor</a></code> implementations in <code><a class="el" href="serialization_8hpp.html" title="Conversion between C++ types and JSON values. ">jsonv/serialization.hpp</a></code>, so you should be able to find one that fits your needs.</p>
<div class="fragment"><div class="line"><a class="code" href="classjsonv_1_1formats.html">jsonv::formats</a> local_formats;</div><div class="line">local_formats.<a class="code" href="classjsonv_1_1formats.html#aaf6e36e4e7edc4702294a4e039113c62">register_extractor</a>(my_type::get_extractor());</div><div class="line"><a class="code" href="classjsonv_1_1formats.html">jsonv::formats</a> format = <a class="code" href="classjsonv_1_1formats.html#ae8fdc86436f8dcfd405753db55620110">jsonv::formats::compose</a>({ <a class="code" href="classjsonv_1_1formats.html#ad194791e293229fb6a79438a6444f51b">jsonv::formats::defaults</a>(), local_formats });</div></div><!-- fragment --><p>Now things are starting to get interesting. The <code><a class="el" href="classjsonv_1_1formats.html" title="Simply put, this class is a collection of extractor and serializer instances. ">jsonv::formats</a></code> object is a collection of <code><a class="el" href="classjsonv_1_1extractor.html" title="An extractor holds the method for converting a value into an arbitrary C++ type. ">jsonv::extractor</a></code>s, so we create one of our own and add the <code><a class="el" href="classjsonv_1_1extractor.html" title="An extractor holds the method for converting a value into an arbitrary C++ type. ">jsonv::extractor</a>*</code> from the static function of <code>my_type</code>. Now, <code>local_formats</code> <em>only</em> knows how to extract instances of <code>my_type</code> &ndash; it does <em>not</em> know even the most basic things like how to extract an <code>int</code>. We use <code><a class="el" href="classjsonv_1_1formats.html#ae8fdc86436f8dcfd405753db55620110" title="Create a new (empty) formats using the bases as backing formats. ">jsonv::formats::compose</a></code> to create a new instance of <code><a class="el" href="classjsonv_1_1formats.html" title="Simply put, this class is a collection of extractor and serializer instances. ">jsonv::formats</a></code> that combines the qualities of <code>local_formats</code> (which knows how to deal with <code>my_type</code>) and the <code><a class="el" href="classjsonv_1_1formats.html#ad194791e293229fb6a79438a6444f51b" title="Get the default formats instance. ">jsonv::formats::defaults</a></code> (which knows how to deal with things like <code>int</code> and <code>std::string</code>). The <code>formats</code> instance now has the power to do everything we need!</p>
<div class="fragment"><div class="line">my_type x = jsonv::extract&lt;my_type&gt;(val, format);</div></div><!-- fragment --><p>This is not terribly different from the example before, but now we are explicitly passing a <code><a class="el" href="classjsonv_1_1formats.html" title="Simply put, this class is a collection of extractor and serializer instances. ">jsonv::formats</a></code> object to the function. If we had not provided <code>format</code> as an argument here, the function would have thrown a <code><a class="el" href="classjsonv_1_1extraction__error.html" title="Exception thrown if there is any problem running extract. ">jsonv::extraction_error</a></code> complaining about how it did not know how to extract a <code>my_type</code>.</p>
<h2><a class="anchor" id="serialization_to_json"></a>
Serialization with to_json</h2>
<p>JSON Voorhees also allows you to convert from your C++ structures into JSON values, using <code>jsonv::to_json</code>. It should feel like a mirror <code>jsonv::extract</code>, with similar argument types and many shared concepts. Just like extraction, <code>jsonv::to_json</code> uses the <code><a class="el" href="classjsonv_1_1formats.html" title="Simply put, this class is a collection of extractor and serializer instances. ">jsonv::formats</a></code> class, but it uses a <code><a class="el" href="classjsonv_1_1serializer.html" title="A serializer holds the method for converting an arbitrary C++ type into a value. ">jsonv::serializer</a></code> to convert from C++ into JSON.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="serialization_8hpp.html">jsonv/serialization.hpp</a>&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="serialization__util_8hpp.html">jsonv/serialization_util.hpp</a>&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="value_8hpp.html">jsonv/value.hpp</a>&gt;</span></div><div class="line"></div><div class="line"><span class="preprocessor">#include &lt;iostream&gt;</span></div><div class="line"></div><div class="line"><span class="keyword">class </span>my_type</div><div class="line">{</div><div class="line"><span class="keyword">public</span>:</div><div class="line">    my_type(<span class="keywordtype">int</span> a, <span class="keywordtype">int</span> b, std::string c) :</div><div class="line">            a(a),</div><div class="line">            b(b),</div><div class="line">            c(<a class="code" href="namespacestd.html">std</a>::move(c))</div><div class="line">    { }</div><div class="line">    </div><div class="line">    <span class="keyword">static</span> <span class="keyword">const</span> <a class="code" href="classjsonv_1_1serializer.html">jsonv::serializer</a>* get_serializer()</div><div class="line">    {</div><div class="line">        <span class="keyword">static</span> <span class="keyword">auto</span> instance = jsonv::make_serializer&lt;my_type&gt;</div><div class="line">                               (</div><div class="line">                                [] (<span class="keyword">const</span> <a class="code" href="classjsonv_1_1serialization__context.html">jsonv::serialization_context</a>&amp; context, <span class="keyword">const</span> my_type&amp; <span class="keyword">self</span>)</div><div class="line">                                {</div><div class="line">                                    <span class="keywordflow">return</span> <a class="code" href="group__Value.html#gabae5c5bfa8dceec8849cfe0a58ad83b1">jsonv::object</a>({ { <span class="stringliteral">&quot;a&quot;</span>, context.to_json(<span class="keyword">self</span>.a) },</div><div class="line">                                                           { <span class="stringliteral">&quot;b&quot;</span>, context.to_json(<span class="keyword">self</span>.b) },</div><div class="line">                                                           { <span class="stringliteral">&quot;c&quot;</span>, context.to_json(<span class="keyword">self</span>.c) }</div><div class="line">                                                         }</div><div class="line">                                                        );</div><div class="line">                                }</div><div class="line">                               );</div><div class="line">        <span class="keywordflow">return</span> &amp;instance;</div><div class="line">    }</div><div class="line">    </div><div class="line"><span class="keyword">private</span>:</div><div class="line">    <span class="keywordtype">int</span>         a;</div><div class="line">    <span class="keywordtype">int</span>         b;</div><div class="line">    std::string c;</div><div class="line">};</div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main()</div><div class="line">{</div><div class="line">    <a class="code" href="classjsonv_1_1formats.html">jsonv::formats</a> local_formats;</div><div class="line">    local_formats.<a class="code" href="classjsonv_1_1formats.html#a2cff39889701f38d7e09a05f01c5ebc7">register_serializer</a>(my_type::get_serializer());</div><div class="line">    <a class="code" href="classjsonv_1_1formats.html">jsonv::formats</a> format = <a class="code" href="classjsonv_1_1formats.html#ae8fdc86436f8dcfd405753db55620110">jsonv::formats::compose</a>({ <a class="code" href="classjsonv_1_1formats.html#ad194791e293229fb6a79438a6444f51b">jsonv::formats::defaults</a>(), local_formats });</div><div class="line">    </div><div class="line">    my_type x(5, 6, <span class="stringliteral">&quot;Hello&quot;</span>);</div><div class="line">    std::ostream &lt;&lt; <a class="code" href="group__Serialization.html#gaabee8db6887a255c3b351d127bfad140">jsonv::to_json</a>(x, format) &lt;&lt; std::endl;</div><div class="line">}</div></div><!-- fragment --><p>Output:</p>
<div class="fragment"><div class="line">{<span class="stringliteral">&quot;a&quot;</span>:5,<span class="stringliteral">&quot;b&quot;</span>:6,<span class="stringliteral">&quot;c&quot;</span>:<span class="stringliteral">&quot;Hello&quot;</span>}</div></div><!-- fragment --><h2><a class="anchor" id="serialization_composition"></a>
Composing Type Adapters</h2>
<p>Does all this seem a little bit <em>manual</em> to you? Creating an <code>extractor</code> and <code>serializer</code> for every single type can get a little bit tedious. Unfortunately, until C++ has a standard way to do reflection, we must specify the conversions manually. However, there <em>is</em> an easier way! That way is the <a class="el" href="serialization_builder_dsl.html">Serialization Builder DSL</a>.</p>
<p>Let's start with a couple of simple structures:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>foo</div><div class="line">{</div><div class="line">    <span class="keywordtype">int</span>         a;</div><div class="line">    <span class="keywordtype">int</span>         b;</div><div class="line">    std::string c;</div><div class="line">};</div><div class="line"></div><div class="line"><span class="keyword">struct </span>bar</div><div class="line">{</div><div class="line">    foo         x;</div><div class="line">    foo         y;</div><div class="line">    std::string z;</div><div class="line">    std::string w;</div><div class="line">};</div></div><!-- fragment --><p>Let's make a <code>formats</code> for them using the DSL:</p>
<div class="fragment"><div class="line"><a class="code" href="classjsonv_1_1formats.html">jsonv::formats</a> formats =</div><div class="line">    <a class="code" href="classjsonv_1_1formats__builder.html">jsonv::formats_builder</a>()</div><div class="line">        .type&lt;foo&gt;()</div><div class="line">            .member(<span class="stringliteral">&quot;a&quot;</span>, &amp;foo::a)</div><div class="line">            .member(<span class="stringliteral">&quot;b&quot;</span>, &amp;foo::b)</div><div class="line">                .default_value(10)</div><div class="line">            .member(<span class="stringliteral">&quot;c&quot;</span>, &amp;foo::c)</div><div class="line">        .type&lt;bar&gt;()</div><div class="line">            .member(<span class="stringliteral">&quot;x&quot;</span>, &amp;bar::x)</div><div class="line">            .member(<span class="stringliteral">&quot;y&quot;</span>, &amp;bar::y)</div><div class="line">            .member(<span class="stringliteral">&quot;z&quot;</span>, &amp;bar::z)</div><div class="line">                .since(<a class="code" href="structjsonv_1_1version.html">jsonv::version</a>(2, 0))</div><div class="line">            .member(<span class="stringliteral">&quot;w&quot;</span>, &amp;bar::w)</div><div class="line">                .until(<a class="code" href="structjsonv_1_1version.html">jsonv::version</a>(5, 0))</div><div class="line">    ;</div></div><!-- fragment --><p>What is going on there? The giant chain of function calls is building up a collection of type adapters into a <code>formats</code> for you. The indentation shows the intent &ndash; the <code>.member("a", &amp;foo::a)</code> is attached to the type <code>adapter</code> for <code>foo</code> (if you tried to specify <code>&amp;bar::y</code> in that same place, it would fail to compile). Each function call returns a reference back to the builder so you can chain as many of these together as you want to. The <code><a class="el" href="classjsonv_1_1formats__builder.html">jsonv::formats_builder</a></code> is a proper object, so if you wish to spread out building your type adapters into multiple functions, you can do that by passing around an instance.</p>
<p>The two most-used functions are <code>type</code> and <code>member</code>. <code>type</code> defines a <code><a class="el" href="classjsonv_1_1adapter.html" title="An adapter is both an extractor and a serializer. ">jsonv::adapter</a></code> for the C++ class provided at the template parameter. All of the calls before the second <code>type</code> call modify the adapter for <code>foo</code>. There, we attach members with the <code>member</code> function. This tells the <code>formats</code> how to encode and extract each of the specified members to and from a JSON object using the provided string as the key. The extra function calls like <code>default_value</code>, <code>since</code> and <code>until</code> are just a could of the many functions available to modify how the members of the type get transformed.</p>
<p>The <code>formats</code> we built would be perfectly capable of serializing to and extracting from this JSON document:</p>
<div class="fragment"><div class="line">{</div><div class="line">    <span class="stringliteral">&quot;x&quot;</span>: { <span class="stringliteral">&quot;a&quot;</span>: 50, <span class="stringliteral">&quot;b&quot;</span>: 20, <span class="stringliteral">&quot;c&quot;</span>: <span class="stringliteral">&quot;Blah&quot;</span> },</div><div class="line">    <span class="stringliteral">&quot;y&quot;</span>: { <span class="stringliteral">&quot;a&quot;</span>: 10,          <span class="stringliteral">&quot;c&quot;</span>: <span class="stringliteral">&quot;No B?&quot;</span> },</div><div class="line">    <span class="stringliteral">&quot;z&quot;</span>: <span class="stringliteral">&quot;Only serialized in 2.0+&quot;</span>,</div><div class="line">    <span class="stringliteral">&quot;w&quot;</span>: <span class="stringliteral">&quot;Only serialized before 5.0&quot;</span></div><div class="line">}</div></div><!-- fragment --><p>For a more in-depth reference, see the <a class="el" href="serialization_builder_dsl.html">Serialization Builder DSL page</a>.</p>
<h1><a class="anchor" id="demo_algorithm"></a>
Algorithms</h1>
<p>JSON Voorhees takes a "batteries included" approach. A few building blocks for powerful operations can be found in the <code><a class="el" href="algorithm_8hpp.html" title="A collection of algorithms a la &lt;algorithm&gt;. ">algorithm.hpp</a></code> header file.</p>
<p>One of the simplest operations you can perform is the <code>map</code> operation. This operation takes in some <code><a class="el" href="classjsonv_1_1value.html" title="Represents a single JSON value, which can be any one of a potential kind, each behaving slightly diff...">jsonv::value</a></code> and returns another. Let's try it.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="algorithm_8hpp.html">jsonv/algorithm.hpp</a>&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="value_8hpp.html">jsonv/value.hpp</a>&gt;</span></div><div class="line"></div><div class="line"><span class="preprocessor">#include &lt;iostream&gt;</span></div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main()</div><div class="line">{</div><div class="line">    <a class="code" href="classjsonv_1_1value.html">jsonv::value</a> x = 5;</div><div class="line">    std::cout &lt;&lt; <a class="code" href="group__Algorithm.html#ga6f0abfde4a15bb3d727727d17e055d4d">jsonv::map</a>([] (<span class="keyword">const</span> <a class="code" href="classjsonv_1_1value.html">jsonv::value</a>&amp; y) { <span class="keywordflow">return</span> y.<a class="code" href="classjsonv_1_1value.html#acfbb2db2ddd7746690c3db702442300b">as_integer</a>() * 2; }, x) &lt;&lt; std::endl;</div><div class="line">}</div></div><!-- fragment --><p>If everything went right, you should see a number:</p>
<div class="fragment"><div class="line">10</div></div><!-- fragment --><p>Okay, so that was not very interesting. To be fair, that is not the most interesting example of using <code>map</code>, but it is enough to get the general idea of what is going on. This operation is so common that it is a member function of <code>value</code> as <code><a class="el" href="group__Algorithm.html#ga9e2e68ce801ca3c29f80f104dd12c99d" title="Run a function over the values of this instance. ">jsonv::value::map</a></code>. Let's make things a bit more interesting and <code>map</code> an <code>array</code>...</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="value_8hpp.html">jsonv/value.hpp</a>&gt;</span></div><div class="line"></div><div class="line"><span class="preprocessor">#include &lt;iostream&gt;</span></div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main()</div><div class="line">{</div><div class="line">    std::cout &lt;&lt; <a class="code" href="group__Value.html#ga8c4ac5022703a328eddc667d4ce333ed">jsonv::array</a>({ 1, 2, 3, 4, 5 })</div><div class="line">                        .<a class="code" href="group__Algorithm.html#ga6f0abfde4a15bb3d727727d17e055d4d">map</a>([] (<span class="keyword">const</span> <a class="code" href="classjsonv_1_1value.html">jsonv::value</a>&amp; y) { <span class="keywordflow">return</span> y.<a class="code" href="classjsonv_1_1value.html#acfbb2db2ddd7746690c3db702442300b">as_integer</a>() * 2; })</div><div class="line">              &lt;&lt; std::endl;</div><div class="line">}</div></div><!-- fragment --><p>Now we're starting to get somewhere!</p>
<div class="fragment"><div class="line">[2,4,6,8,10]</div></div><!-- fragment --><p>The <code>map</code> function maps over whatever the contents of the <code><a class="el" href="classjsonv_1_1value.html" title="Represents a single JSON value, which can be any one of a potential kind, each behaving slightly diff...">jsonv::value</a></code> happens to be and returns something for you based on the <code>kind</code>. This simple concept is so ubiquitous that <a href="http://www.disi.unige.it/person/MoggiE/">Eugenio Moggi</a> named it a <a href="http://stackoverflow.com/questions/44965/what-is-a-monad">monad</a>. If you're feeling adventurous, try using <code>map</code> with an <code>object</code> or chaining multiple <code>map</code> operations together.</p>
<p>Another common building block is the function <code>jsonv::traverse</code>. This function walks a JSON structure and calls a some user-provided function.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="algorithm_8hpp.html">jsonv/algorithm.hpp</a>&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="parse_8hpp.html">jsonv/parse.hpp</a>&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="value_8hpp.html">jsonv/value.hpp</a>&gt;</span></div><div class="line"></div><div class="line"><span class="preprocessor">#include &lt;iostream&gt;</span></div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main()</div><div class="line">{</div><div class="line">    <a class="code" href="group__Algorithm.html#gaf74e9854143e94b2b014efe15eb63fdf">jsonv::traverse</a>(jsonv::parse(std::cin),</div><div class="line">                    [] (<span class="keyword">const</span> <a class="code" href="classjsonv_1_1path.html">jsonv::path</a>&amp; path, <span class="keyword">const</span> <a class="code" href="classjsonv_1_1value.html">jsonv::value</a>&amp; value)</div><div class="line">                    {</div><div class="line">                        std::cout &lt;&lt; path &lt;&lt; <span class="stringliteral">&quot;=&quot;</span> &lt;&lt; value &lt;&lt; std::endl;</div><div class="line">                    },</div><div class="line">                    true</div><div class="line">                   );</div><div class="line">}</div></div><!-- fragment --><p>Now we have a tiny little program! Here's what happens when I pipe <code>{ "bar": [1, 2, 3], "foo": "hello" }</code> into the program:</p>
<div class="fragment"><div class="line">.bar[0]=1</div><div class="line">.bar[1]=2</div><div class="line">.bar[2]=3</div><div class="line">.foo=<span class="stringliteral">&quot;hello&quot;</span></div></div><!-- fragment --><p>Imagine the possibilities!</p>
<p>All of the <em>really</em> powerful functions can be found in <code><a class="el" href="util_8hpp.html" title="Deprecated. ">util.hpp</a></code>. My personal favorite is <code>jsonv::merge</code>. The idea is simple: it merges two (or more) JSON values into one.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="util_8hpp.html">jsonv/util.hpp</a>&gt;</span></div><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="value_8hpp.html">jsonv/value.hpp</a>&gt;</span></div><div class="line"></div><div class="line"><span class="preprocessor">#include &lt;iostream&gt;</span></div><div class="line"></div><div class="line"><span class="keywordtype">int</span> main()</div><div class="line">{</div><div class="line">    <a class="code" href="classjsonv_1_1value.html">jsonv::value</a> a = <a class="code" href="group__Value.html#gabae5c5bfa8dceec8849cfe0a58ad83b1">jsonv::object</a>({ { <span class="stringliteral">&quot;a&quot;</span>, <span class="stringliteral">&quot;taco&quot;</span> }, { <span class="stringliteral">&quot;b&quot;</span>, <span class="stringliteral">&quot;cat&quot;</span> } });</div><div class="line">    <a class="code" href="classjsonv_1_1value.html">jsonv::value</a> b = <a class="code" href="group__Value.html#gabae5c5bfa8dceec8849cfe0a58ad83b1">jsonv::object</a>({ { <span class="stringliteral">&quot;c&quot;</span>, <span class="stringliteral">&quot;burrito&quot;</span> }, { <span class="stringliteral">&quot;d&quot;</span>, <span class="stringliteral">&quot;dog&quot;</span> } });</div><div class="line">    <a class="code" href="classjsonv_1_1value.html">jsonv::value</a> merged = <a class="code" href="group__Algorithm.html#gac0b85875aad4cd7b63bf9100a65f2139">jsonv::merge</a>(std::move(a), std::move(b));</div><div class="line">    std::cout &lt;&lt; merged &lt;&lt; std::endl;</div><div class="line">}</div></div><!-- fragment --><p>Output:</p>
<div class="fragment"><div class="line">{<span class="stringliteral">&quot;a&quot;</span>:<span class="stringliteral">&quot;taco&quot;</span>,<span class="stringliteral">&quot;b&quot;</span>:<span class="stringliteral">&quot;cat&quot;</span>,<span class="stringliteral">&quot;c&quot;</span>:<span class="stringliteral">&quot;burrito&quot;</span>,<span class="stringliteral">&quot;d&quot;</span>:<span class="stringliteral">&quot;dog&quot;</span>}</div></div><!-- fragment --><p>You might have noticed the use of <code>std::move</code> into the <code>merge</code> function. Like most functions in JSON Voorhees, <code>merge</code> takes advantage of move semantics. In this case, the implementation will move the contents of the values instead of copying them around. While it may not matter in this simple case, if you have large JSON structures, the support for movement will save you a ton of memory.</p>
<dl class="section see"><dt>See also</dt><dd><a href="https://github.com/tgockel/json-voorhees">https://github.com/tgockel/json-voorhees</a> </dd>
<dd>
<a href="http://json.org/">http://json.org/</a> </dd></dl>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.13 </li>
  </ul>
</div>
</body>
</html>
